🖌️

Filecoin Retrieval Provider Blueprint

Filecoin Beam architecture and beyond

Author: Miroslav Bajtoš <miroslav@meridian.space>

Last updated:

Introduction

On Tuesday, November 18, 2025, the FilOz and FilBeam teams were getting ready for the big announcement at the De:PIN day in Buenos Aires. As we were setting up the booth to let visitors take a selfie and pin it via IPFS to Filecoin Onchain Cloud, we discovered that Cloudflare went down, and the demo web app hosted on Cloudflare no longer works. Fortunately, the app was designed in a way that made it easy to move it to a different website hosting service (eth.limo).

The storage layer was running on Filecoin Onchain Cloud, which was already a decentralised platform with no single point of failure. We were able to quickly switch website hosting providers and restore the demo before the first attendees arrived.

In contrast, FilBeam is tightly coupled with the Cloudflare platform. Our early adopters didn’t have any other choice but to wait until Cloudflare restored its service and FilBeam became operational again.

We need to do better.

How can we build a more resilient world where an outage of any large provider, like Cloudflare or AWS, does not bring down half of the internet?

The first idea that comes to many minds is to build the retrieval layer as a decentralised network of nodes operated by independent entities, so that no node is a single point of failure. There are two problems making such a design infeasible:

  1. Most retrieval clients are “dumb” - they need a single URL, a single location from which to obtain the content. Solutions like anycast allow us to push the control plane down to the internet routing level, avoiding a single point of failure. However, to enable HTTPS retrievals, every retrieval node must have a valid TLS certificate for the same domain name. This is a dangerous proposition when the nodes are not trusted and can be operated by adversaries.
  1. It was proven that a fair exchange is impossible without a trusted party [1]. With a decentralised network of retrieval nodes, we have to trust each retrieval node to act honestly and provide a good retrieval service. That is not realistic, as we painfully learned while building Saturn, the decentralised CDN for Filecoin (docs).

We believe that retrieval infrastructure needs a different model, one that’s closer to how the storage infrastructure works in Filecoin: A market of service providers allowing clients to choose the provider that matches their needs and their budget.

In such a world, FilBeam on Cloudflare will be one of many available options. When FilBeam goes down, clients can easily switch to a different retrieval provider, similarly to how web2 sites can switch between different CDNs. Because the data is content-addressed and stored on Filecoin Onchain Cloud, the migration to a different retrieval provider should be seamless. Other networks like Storj, Arweave and Walrus already use a similar model, where the clients must trust the retrieval gateway they interact with, but there are many such gateways available.

We wrote this document to share our knowledge about building a retrieval provider for the Filecoin Onchain Cloud and inspire other teams to create and run alternate retrieval providers.

What is FilBeam (and What It’s Not)

Before we jump into technical details, it’s important to understand that FilBeam’s first and foremost goal is an incentivised retrieval layer that pays Storage Providers for their retrieval services.

Everything else comes second, as support for the main goal:

  • Improved retrieval success rate as observed by clients, thanks to FilBeam implementing a fallback to backup storage providers on retrieval failures.
  • Improved retrieval response times, thanks to FilBeam caching the content all around the world in a CDN-like fashion and maintaining an index of on-chain state on the edge nodes.
  • Service Provider reputation based on the quality of retrieval service, as observed by FilBeam during cache-miss requests for real user traffic. We can leverage this to incentivise good behaviour, which will become critical as Filecoin Onchain Cloud grows beyond the initial group of trusted service providers.

Filecoin Onchain Cloud Architecture

Please note that the architecture is still evolving; this description is accurate as of December 2025.

Let’s start by describing the relevant subset of FOC components that FilBeam depends on. You can learn more details in the official documentation at https://docs.filecoin.cloud/core-concepts/architecture/.

Data Set Initialisation

Filecoin Beam provides access to content stored using the Warm Storage service. Before the user can upload their first file, they have to set up a DataSet (think of an AWS S3 Bucket) linked to payments. When creating a new data set, the user must authorise ongoing payments for the services linked to the data set - storage costs and optionally FilBeam egress costs.

All data sets have a payment rail between the customer and the service provider to pay for storage. As part of data set initialisation, a small amount of funds is locked into this rail. The warm storage service handles storage payments; the details are not relevant here.

When creating a data set, the user can enable Filecoin Beam retrieval services for all files in the data set by adding metadata withCDN: true. In such a case, data set initialisation creates two more payment rails:

  • A payment rail between the customer and the service provider to pay for cache-miss egress, controlled by Filecoin Beam. A small amount of funds is locked into this rail at the time of creation; the customer can later buy more egress.
  • A payment rail between the customer and Filecoin Beam for content distribution services, controlled by Filecoin Beam. A small amount of funds is locked into this rail at the time of creation; the customer can later buy more egress.

Egress payments are handled by the FilBeam operator smart contract, see the section below. This contract tracks egress consumption and provides methods for FilBeam and the SP to settle payments for their services.

After the data set was successfully initialised, the FilecoinWarmStorageService smart contract emits the event DataSetCreated.

Piece Creation

Now the user can add files (pieces) to this data set. After a new Piece was successfully added, the FilecoinWarmStorageService smart contract emits the event PieceAdded.

Piece Deletion

There is a similar process for deleting a file (removing a piece from the data set). The FilecoinWarmStorageService smart contract does not emit any events for this operation yet, observers can listen for the PDPVerifier’s event PiecesRemoved.

Both the PDPVerifier and WarmStorageService contracts emit events related to datasets and pieces. The distinction is that PDPVerifier does not process the metadata; consumers of these events must validate the client signature and deserialise the metadata bytes themselves. On the other hand, the WarmStorageService contract validates the metadata and provides metadata as a list of key-value pairs in the event payloads.

Service termination

The client can decide to terminate the service, i.e. delete the entire data set. In such case, the FilecoinWarmStorageService contract emits the events CDNServiceTerminated and ServiceTerminated.

Additionally, when Filecoin Beam detects that the user’s wallet address has been flagged as sanctioned, it terminates the FilBeam service only, while keeping the storage service. The FilecoinWarmStorageService contract emits the event CDNServiceTerminated.

Egress Allowance Top-Ups

When the user adds more funds to get additional egress allowance, the FilecoinWarmStorageService contract updates the locked funds in the corresponding payment rails and emits the event CDNPaymentRailsToppedUp.

Settlement of Payments

Each Service Provider and FilBeam can settle egress payments by calling a method on the FilBeamOperator contract. FilBeam does not need to observe these settlement operations.

Service Provider Registry

To retrieve a piece, we need the Service Provider’s base URL to construct the piece retrieval URL.

Service Provider metadata is maintained in the ServiceProviderRegistry smart contract. For each provider, there is a list of products they offer. Filecoin Beam supports only one product type PDP (value 0).

Each product has a key-value list of capabilities. The Service Provider’s base URL is indicated in the product capability called serviceURL.

Filecoin Beam Architecture

Please note that the architecture is still evolving; this description is accurate as of December 2025.

Filecoin Beam is implemented as a serverless service running on Cloudflare Workers, using Cloudflare D1 & KV for storage, and relying on Cloudflare’s CDN network and caching for fast content delivery.

Indexer

To handle retrieval requests as quickly as possible, Filecoin Beam indexes on-chain events to build a local view of the state of Filecoin Pay and FilecoinWarmStorageService entities. We are using Goldsky subgraphs and pipelines to listen for selected events and send them to Beam’s webhooks.

The subgraph has a simple data model mapping events to subgraph entities in a 1:1 fashion, applying lightweight datatype conversions where necessary.

List of contracts and events we are indexing:

  • ServiceProviderRegistry
    • ProductAdded
    • ProductUpdated
    • ProductRemoved
    • ProviderRemoved
  • PDPVerifier
    • PiecesRemoved
  • FilecoinWarmStorageService
    • DataSetCreated
    • PieceAdded
    • ServiceTerminated
    • CdnServiceTerminated
    • CdnPaymentRailsToppedUp

For each event, there is a component in our Goldsky pipeline that sends the event payload to the appropriate webhook, configured to send a single event per request.

On the FilBeam side, the indexer worker provides webhook handlers that keep our database in sync with the on-chain state.

Piece Retrievals

Database Schema

Piece retrievals require the following three tables to be kept up to date by the indexer component:

service_providers

  • id
  • service_url

data_sets

  • id
  • service_provider_id (referencing service_providers.id)
  • payer_address
  • with_cdn

pieces

  • id
  • data_set_id (referencing data_sets.id)
  • cid

Additionally, to enable pay-per-byte billing, we have another table keeping track of the egress allowances:

data_set_egress_quotas

  • data_set_id (referencing data_sets.id)
  • cdn_egress_quota
  • cache_miss_egress_quota

Finally, we are recording every retrieval request to provide us with telemetry, usage statistics, and accurate egress consumption.

retrieval_logs

  • id
  • timestamp
  • data_set_id (referencing data_sets.id)
  • egress_bytes
  • cache_miss
  • (etc.)

Retrieval request

When the user requests a file via Filecoin Beam:

sequenceDiagram
	participant U as User
	participant RW as FilBeam Retrieval Worker
	participant DB as FilBeam DB
	participant CFC as Cloudflare Cache
	participant SP as Service Provider
	
U ->> RW: Request content (wallet, cid)
RW ->> DB: Look up Data Set, Piece and Service Provider
RW ->> DB: Check remaining CDN egress allowance
RW ->> CFC: Check if the content is cached
alt Cache-hit
CFC ->> RW: Return content
else Cache-miss
CFC ->> RW: Not found
RW ->> DB: Check remaining cache-miss egress allowance
RW ->> SP: Request content
SP ->> RW: Respond with content
RW ->> CFC: Write the content to the cache
end
RW ->> U: Respond with content
RW ->> DB: Record egress used (CDN, cache-miss)
RW ->> DB: Update remaining egress allowances (CDN, cache-miss)

When a request comes in from the User, FilBeam does a lookup and then checks the remaining egress. In the lookup step, we need to map (wallet, cid) provided by the user to the Data Set, Piece, and Service Provider:

  1. We select data_sets where payer matches the wallet.
  1. We select pieces where cid matches the cid.
  1. We join these two sets using the data_set_id column.
  1. And finally, we add the service provider’s URL by joining the service_providers table using the provider_id column.

To check the remaining egress allowances, we consult the table data_set_egress_quotas.

After the request was handled, we record egress consumption by inserting a new row to retrieval_logs table and updating the appropriate row in data_set_egress_quotas.

Egress Accounting

Indexing Egress Top-Ups

Whenever the user locks funds to pre-pay egress consumption, the smart contract emits an event CdnPaymentRailsToppedUp with details about the locked amounts. The Goldsky pipeline forwards the event to our indexer webhook, which updates the data data_set_egress_quotas accordingly.

Reporting Egress Consumption

Filecoin Beam periodically submits egress consumption data from its off-chain database to the FilBeamOperator contract. The calibnet deployment reports egress consumption every 30 minutes, while the mainnet deployment reports it every 4 hours.

For each data set for which the egress consumption was reported, the FilBeamOperator contract updates the amounts owed by the client to FilBeam and the Service Provider.

Legal Compliance

In the sections above, we described the core flows for serving retrievals. In order to meet regulatory requirements, we had to build two additional components: sanctions checks and bad-bits checks.

Sanction checks

To comply with sanctions and anti-money laundering rules, we must not accept payments from wallets that are sanctioned or linked to illegal activities.

We do that by periodically calling the Chainalysis Sanctions Screening API for every wallet in our index and storing the screening result in the database.

The retrieval worker consults this data for every incoming request and rejects requests for sanctioned wallets.

Additionally, when we detect that a wallet has been flagged as sanctioned, we terminate CDN services by calling the appropriate smart-contract method.

Bad-bits

When a service allows people to upload and retrieve any content, someone will inevitably upload malware, copyrighted material, or content flagged for other reasons. The service operator is expected to remove that content, e.g., upon receiving a takedown request.

Thanks to content addressing, we don’t have to wait for a takedown request - we can proactively identify protected content by consulting the Bad Bits Denylist.

Filecoin Beam periodically fetches the latest denylist version to maintain a list of flagged CIDs in our database.

The retrieval worker consults this list for every incoming request and rejects requests for flagged CIDs.

IPFS Retrievals

As an experimental feature available on the calibration testnet, FilBeam provides an IPFS HTTP Gateway for retrieving IPFS content stored on Filecoin, e.g. uploaded via filecoin-pin.

On the indexer side, we augment the data_sets table with a new column with_ipfs_indexing that’s populated from data set metadata withIPFSIndexing, and the pieces table with a new column ipfs_root_cid populated from piece metadata ipfsRootCID.

On the retrieval side, we implemented a new retrieval worker that uses IPFS Root CID instead of the Piece CID when mapping the user request to a warm storage deal.

Missing Pieces

At the moment, Filecoin Warm Storage Service and Filecoin Beam are tightly coupled at the smart contract level. While other retrieval services can listen for smart contract events to understand what content is stored on the Filecoin Onchain Cloud, the payment layer does not allow such services to be included in the warm storage deals.

In order to allow alternative retrieval services to emerge, we need to redesign Filecoin Onchain Cloud into a modular architecture that allows developers to pick and mix arbitrary services.

As part of this new design, we will need a way to allow Service Providers to approve which Retrieval Providers they trust to report accurate egress usage for payment purposes.

FilBeam and FilOz teams are periodically discussing this topic (code name: PDPBoss). There was a session at FilDevSummit in Buenos Aires, and there are preliminary plans to implement these changes in 2026.

An alternative approach is to adopt x402 micropayments on the Service Provider side, with a micropayment authorisation accompanying each retrieval request. This micropayment will cover the egress costs incurred by the SP, not the fee charged by the creator to access the content. In such a case, the SP does not need to trust the Retrieval Provider to report accurate egress usage, and thus does not need to approve the Retrieval Providers they are willing to work with.

Lite Retrieval Node

FilBeam architecture is complex and tightly coupled to a centralised cloud platform (Cloudflare). In return, we get fast retrievals from anywhere in the world. It’s one of the possible tradeoffs.

In this section, we explore a different trade-off: a network of nodes with no shared state, which enables additional design options for retrieval clients.

  • A smart client can maintain a list of retrieval nodes in this network, request content directly from individual nodes, and implement a fallback mechanism if a node goes down.
  • We can add a DNS-based load-balancing layer in front of this network to allow location-based retrievals - e.g. paste a single URL into the browsers and let the load-balancer route the request to the closest node. (This load-balancer will become a point of failure, but that’s unavoidable.)

Such architecture makes it easy to spin up a new retrieval network: choose a Subgraph provider, deploy a Docker container across multiple machines in different geographical regions, configure DNS-based load balancing (or an IP anycast network), and you have a new retrieval provider available. (In practice, you will also need to deploy a smart contract to operate the payment rails, and tell customers to configure Synapse SDK to use this new retrieval provider, but that’s out of scope of this section. See also above.)

This is still a trusted setup - every node in the network is fully trusted to act honestly. However, the architecture makes it easy for 3rd parties to set up their own retrieval networks, allowing Filecoin customers to choose which one to use. In other words, decentralisation is at the level of retrieval providers (networks of nodes), not at the level of individual nodes. If people don’t trust a particular retrieval node or network, they can use another one.

ℹ️

The proposal is a starting point, the foundation that can be incrementally improved to reduce the performance gap between the node-based architecture and the Cloudflare-based architecture.

The key difference between FilBeam and Lite Retrieval Node lies in how they consume on-chain deal metadata during the retrieval process.

  • Filecoin Beam wants to provide fast, web2-grade performance. Therefore, it proactively indexes all deals and keeps a local copy of the state on every edge node. This depends on Cloudflare’s storage layer, which makes it easy to access data from every edge node, but also creates a single point of failure.
  • For Lite Retrieval Nodes, we prioritise resiliency. We want each node to be self-contained and not depend on sharing state with other nodes. We propose a pull-based approach in which the node looks up deal metadata only on the first retrieval request for that deal. To speed up subsequent requests for the same content, the metadata lookup results will be cached locally.

Here is a high-level sequence of the retrieval process:

sequenceDiagram
  participant C as Client
  participant RN as Retrieval Node
  participant OCS as Onchain State
  participant SP as Service Provider
 
 C ->> RN: GET (payer_address, piece_cid)
 RN ->> OCS: query deals matching (payer_address, piece_cid)
 OCS ->> RN: list of deals (incl. metadata)
 RN ->> RN: pick a deal to use (data set, SP)
 RN ->> SP: GET piece_cid
 SP ->> RN: Piece bytes
 RN ->> C: Piece bytes

There are three essential cases we need to consider:

  1. Retrieval Flow: When a retrieval request for (payer_address, cid) arrives, how do we find all the deals made by payer_address and storing cid? Next, how do we obtain the storage provider service URL to retrieve the data?
  1. Metadata Cache Invalidation: How do we invalidate the cached metadata when a deal ends, e.g. a piece was deleted?
  1. Tracking Egress Allowance & Consumption: How do we keep track of egress consumption and update the remaining allowances?

We will look into these cases deeper below.

Retrieval Flow

Obtaining Deal Metadata

In order to get the deal metadata required for handling retrieval requests, we need to query the on-chain state. To make these queries fast and efficient, we need a view into the state of various smart contracts, such as PDPVerifier and WarmStorageService. Maintaining such views in the on-chain state would be too expensive.

We propose building a Subgraph that others can deploy & operate. This Subgraph will index on-chain events and develop a data model that matches the queries. Essentially, this means moving the FilBeam indexer & database part from Cloudflare to Subgraph.

The Subgraph approach gives us the following benefits:

  • Subgraph has become a standard way to index on-chain activity. It makes it easy to take a subgraph definition and stand up a new node providing GraphQL access to the indexed data.
  • Teams operating a network of lite retrieval nodes can choose the subgraph operator that best matches their needs:
    • A hosted offering like Goldsky.
    • Graph’s decentralized network.
    • Self-hosted subgraph indexer, e.g. running alongside each retrieval node.

Querying the subgraph node for every incoming request may be too slow and expensive. To improve response times for frequently accessed content, the retrieval node should cache the results of subgraph queries in memory.

Bad-bits Check

Each lite node should periodically fetch the Bad Bits Denylist and store it in an in-memory lookup table to enable fast checks.

Sanctions Check

Each node should query the Chainalysis Sanctions Screening API to check if the wallet paying for the deal is not sanctioned. The results of these checks should be cached in memory with a reasonably long expiration.

Cache Piece Content

Another easy optimisation of the response time is adding a content cache to each node. This can be a simple file-system-backed cache using the Least Frequently Used or the Least Recently Used eviction strategy. This is easy because of content addressing - the response for each URL (CID) is immutable.

Metadata Cache Invalidation

Service Provider Lookup

There are several cases where we need to invalidate the result of a query for deals matching (payer_address, piece_cid):

  1. The piece was deleted by the user.
  1. The service was terminated by the user.
  1. The service was terminated by the retrieval provider.

We propose setting a short time-to-live for the cached query results (e.g., 60 seconds) and accepting the risk that it may take up to 60 seconds for the retrieval network to notice that some content was deleted. We feel this is an acceptable tradeoff, considering Filecoin’s block time (30 seconds) and time to finality (minutes, thanks to Fast Finality in Filecoin).

In the future, we can explore more advanced approaches like “stale-while-invalidate”, where the node returns the cached response immediately and re-runs the query in the background when the cached response is nearing the expiration time.

Bad-Bits

The list of bad-bits CIDs is periodically updated by a background process. There is no need to invalidate this cache other way.

Sanctions Checks

The check results should have an expiration period that balances the need to detect newly sanctioned addresses quickly with the need to keep API requests below the rate limit. 24 hours should be a good start.

Tracking Egress Allowance & Consumption

It is infeasible to submit egress usage after every retrieval request. In FilBeam, we keep track of egress usage and remaining egress allowances in a database shared by all nodes, and periodically report aggregated usage to the FilecoinBeamOperator smart contract.

In the new node-based architecture:

  • Each network operator will deploy a new copy of the FilecoinBeamOperator smart contract. This contract will authorise all nodes in this network to submit usage data.
  • Each retrieval node must independently track egress usage & allowances, and periodically submit usage data to this network-specific operator contract.

As a result, each network-specific operator contract will aggregate usage data from nodes in that network, in a fully decentralised way with no single points of failure.

However, this exacerbates the race condition in using the chain as the source of truth, where the retrieval network may end up serving more egress than was paid for. Unfortunately, the only bulletproof solution for this problem is to block every retrieval request until the payment is settled (in the x402 style), which is not feasible on Filecoin.

We suggest accepting this risk as part of running the retrieval business. Most clients will eventually top up their egress allowances, at which point the retrieval network can settle the debt created by egress over-usage. As long as the number of clients in debt remains low, the costs should be manageable, and the retrieval provider can cover them from its operational margin.

It is possible to reduce this risk by requiring a minimum remaining egress allowance to serve retrieval requests. For example, refuse to serve further retrievals when the remaining allowance observed by the node drops below N*S, where N is a tunable parameter (e.g. N=10), and S is the average file size stored by the payer.

Future Optimisation Opportunities

  1. Explore the options for sharing cached deal metadata across all retrieval nodes. While it’s possible to avoid sharing state and let each retrieval node rebuild the index from the on-chain or Subgraph state, such a setup could be too expensive and slow down the startup of individual nodes.
    • Replacing the per-node in-memory cache with a shared Redis instance is a straightforward solution, but it creates a new single point of failure.
    • A more resilient approach is to replicate the cached entries across all nodes using a peer-to-peer messaging protocol, e.g. libp2p’s gossipsub.
    • It may be possible to periodically create a snapshot of the index and publish it to the Filecoin Onchain Cloud, so that other nodes can seed their local index from that snapshot at the startup.
  1. Explore Subgraph subscriptions as the solution for cache invalidation - let each retrieval node subscribe to changes in deal metadata and invalidate the cache as soon as the piece is deleted or the service is terminated.
  1. Explore options for retrieval nodes to proactively or periodically index on-chain state. We need to find a cost-effective solution, otherwise the infra costs will linearly grow with the number of retrieval nodes in the network. Subgraph subscriptions could be a potential solution.
  1. Explore how to replace Subgraph with a solution where retrieval nodes call JSON-RPC providers to get updates about the on-chain state, and persist them in their local DB. This should be more resilient and mean less shared state.
    In order to allow nodes to learn about historical deals, we need either:
    1. Have access to an archival node so the node can fetch all historical deals on first start. I believe that archival nodes are expensive to operate, and also, querying historical deals at node startup will be very slow.
    1. Expands the on-chain state to provide a list of all active FOC deals, including Dataset & Piece metadata. This effectively means that every Filecoin node will become a Subgraph provider. That will be even more expensive in gas fees.

Alternatives Considered

Instead of proxying through the bytes, let the retrieval node respond with an HTTP redirect to the SP. While that could be a good hack to ship the first node version quickly, there are several major issues:

  1. We lose the trusted party that tracks egress served.
  1. We lose the caching layer provided by retrieval nodes.
  1. If the SP does not serve the retrieval, it’s up to the client to retry the request. (In the current design, when the SP does not serve the retrieval, the node can retry with a different SP.)

References

[1] Henning Pagnia and Felix C Gartner. On the impossibility of fair exchange without a trusted third party. Technical report, Technical Report TUD-BS-1999-02, Darmstadt University of Technology, Department of Computer Science, Darmstadt, Germany, 1999.

Smart contracts:

FilBeam Subgraph & Pipelines:

FilBeam Cloudflare Workers